home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1997 August / Walnut Creek CDROM.7z / VOL_300 / 351_01 / HELP.ZIP / HELP.DOC next >
Encoding:
Text File  |  1991-10-13  |  13.1 KB  |  229 lines
  1. ************************* Using the EnQue Help Engine ************10/08/91***
  2.  
  3. This file is divided into two parts.  The first describes how to use the
  4. help engine.  The second describes how to create your own help files.
  5.  
  6.   The help engine is very easy to use due to its employment of EnQue's new
  7. user-interface-construction toolkit, InTUItion.  The help may be used with
  8. either the keyboard or mouse.  The help files may consist of simple ASCII
  9. files or have imbedded commands that allow for color control, hypertext
  10. links, sound, etc.  If the files exist in the current directory, that file
  11. is accessed, otherwise, the help engine looks in the path set by the
  12. environment variable ENQHELP.  To set this, add a line to your autoexec.bat
  13. file that looks something like this "set ENQHELP=c:\borlandc\enque".
  14.  
  15.   To invoke the help engine, type "enqhelp filename 0/1 search sx sy ex ey
  16. where the filename is the first file the help engine should access.  The 0
  17. or 1 parameter tells the help engine to read the screen contents and search
  18. for a given keyword.  If you are running help within Borland's compilers,
  19. setting help up as a Transfer program allows you to pull help up for
  20. UltraWin/InTUItion functions.  See "Setting up a transfer program" below.
  21. Search specifies an initial search word if the mode is 0.  Coordinates sx sy
  22. ex ey are screen coordinates for the window that will be used by help.
  23. Default values can be used (1, 4, 78, 20) if no parameters are specified.
  24. The help window must be either wider than 64 characters, or taller than 14.
  25. This is to allow for the dialog interface buttons and sliders.  If the
  26. values are out of range or the file does not exist, the help engine will
  27. return.  The help engine can be invoked with no parameters and will default
  28. to uw_help0.hlp 0 0 1 4 78 20.
  29.  
  30.   Once active, you can scroll around the help file much like an editor.
  31. UP, DOWN, LEFT, RIGHT, HOME, END, PgUp, PgDn, Ctrl-PgUp, Ctrl-PgDn 
  32. allow you to move around the file.  If the file is wider than the help
  33. window you can scroll horizontally as well as vertically.
  34. The buttons operate as follows.  
  35. Search   - [Alt-S] pulls up a dialog to allow you to search for a specific
  36.            word or phrase.
  37. Repeat   - [Alt-R] finds the next occurrence specified by Search.
  38. <<<      - [Shift-Tab] key moves to the previous keyword.
  39. >>>      - [Tab]  moves to the next keyword.
  40. Previous - [Alt-P] moves to the previously active keyword.
  41. Index    - [Alt-I] moves to the original starting place.
  42. Quit     - [Alt-Q] exits the help program.
  43. If you are using a mouse, clicking on the button, sliders, close box,
  44. (upper left corner), or keyword will activate the function.
  45.  
  46.   To move to a keyword, you can use the tab keys or cursor keys to move
  47. to the desired word.  The keyword will highlight.  Pressing enter or double
  48. clicking on this word will take you to additional information on this
  49. topic.  Pressing Alt-P (previous) will take you back one level.
  50.  
  51.  To search for a specific word/phrase, press Alt-S or click on Search.
  52. This pulls up a dialog box.  To enter the word/phrase, press Alt-S again
  53. or click on the string following the word Search.  Type in the word/phrase
  54. and press Alt-O or click on OK.  The default search will search forward
  55. from the current cursor location.  The direction and scope can be changed
  56. by clicking on the appropriate check box or pressing the desired hot-key.
  57. Forward   - [Alt-F] sets the search direction to forward.
  58. Backward  - [Alt-B] sets the search direction to backwards.
  59. From Csr  - [Alt-R] search from current cursor position.
  60. Global    - [Alt-G] search from start of file.
  61. Case      - [Alt-C] if off, case is ignored.
  62. Quit      - [Alt-Q] abort the current search dialog.
  63. OK        - [Alt-O] accept parameters and find first word. 
  64.  
  65. Thats basically it!
  66.  
  67.   Setting up a transfer program - To use the help engine as a transfer 
  68. program for the Borland Compilers, edit the transfer parameters as 
  69. normal (see the Borland Documentation) and for the command line parameters
  70. be sure to type $NOSWAP as the first command.  An example for an EGA 43
  71. row screen would be "$NOSWAP uw_help0.hlp 1 1 20 78 40". 
  72.   If you would like the help engine to "move" directly to the function
  73. that your cursor points to, load the tiny TSR tckbd.com before entering
  74. the compiler.  This is a hook that allows the help engine to read the
  75. word that the cursor points to and search for when invoked.  It is a good
  76. idea to call tckbd.com from you autoexec.bat.  Note that the Borland
  77. compiler requires you to set up the transfer program for each project
  78. file.
  79.   
  80. ************************ Creating your own help files ***********************
  81.  
  82. ------------------------------ Help Commands --------------------------------
  83. Overview:
  84.   The help commands are structured much like a "C" function call with a few
  85. restrictions.  The command must be preceded by a ` character, and no white-
  86. space is allowed within the command.  All commands are stripped from the
  87. help display.  A line within the help text file can contain multiple commands
  88. and can be up to 255 characters in length.  Keep in mind that the displayed
  89. width may be less since commands are stripped.  Also note that no commands
  90. are required, the help may simply consist of ASCII text that is linefeed or
  91. carriage return/linefeed delimited.  These commands are designed to allow
  92. you to enhance your help files and add powerful HyperText capabilities. 
  93.   Since the help files are simply ASCII, they can be edited with virtually
  94. any text editor.  The help engine will accept and display the extended 
  95. character set if desired and if your editor allows the inclusion of these
  96. characters.  This allows you to create borders, etc., within your help
  97. files.  The drawback to ASCII files is a small sacrifice in speed when 
  98. reading/parsing these files.  However, by keeping your help files relatively
  99. small, (which they should be to conserve memory as much as for speed),
  100. this drawback is all but unnoticable.
  101.  
  102. KEYWORD:  `keyword(word,search string);
  103.   There are three forms of the keyword command.  The first specifies the 
  104. actual keyword followed by a search string.  Both the keyword and the search
  105. string can consist of several words (up to 80 characters).  In this form, 
  106. the search string must reside in the same file as the keyword command.  It
  107. can be located anywhere in the file and should be unique.  It is good
  108. practice to use a character or sequence of characters in the search string
  109. that will not commonly occur in the text in order to assure this uniqueness.
  110. For example `keyword(File System,/// The DOS File System);  Here we use
  111. three / to insure the uniqueness of the search string.  Note that the keyword
  112. and search string can be different.
  113.   The second form is like the first but includes a modifier in front of the
  114. search string.  This modifier, enclosed in brackets, specifies the file in
  115. which the search string exists.  For example, `keyword(DOS,[dos.hlp]/// DOS);
  116. This works the same as the example above except that the file dos.hlp will
  117. no be loaded into the help engine and the search string "/// DOS" will be
  118. located.
  119.   The third form is similar to the other two in form but different in action.
  120. When the user moves to this keyword and presses <Enter>, the second parameter
  121. is used as a DOS command and executed.  For example, `keyword(DIR,{dir c:});
  122. When selected, this keyword will execute the DOS command "dir c:".  This
  123. is useful for creating menus, shells, etc.
  124.  
  125. COLOR:  `color(foreground string,background string);
  126.   There are a number of color control commands that allow you to personalize
  127. your help files.  Often, only one or two are used.  The first and most common
  128. is the color command.  Two parameters specify the foreground and background
  129. colors.  For example `color(RED,LIGHTGRAY);  Sixteen colors are available
  130. for each.  Knowledge of the PC text attribute structure is recommended but
  131. not required.  The colors are as follows:
  132.                     Normal           High Intensity
  133.                     -------          --------------
  134.                     0 BLACK           8 DARKGRAY     
  135.                     1 BLUE            9 LIGHTBLUE    
  136.                     2 GREEN          10 LIGHTGREEN   
  137.                     3 CYAN           11 LIGHTCYAN    
  138.                     4 RED            12 LIGHTRED     
  139.                     5 MAGENTA        13 LIGHTMAGENTA 
  140.                     6 BROWN          14 YELLOW       
  141.                     7 LIGHTGRAY      15 WHITE        
  142. The high intensity will cause the text to blink if used as the background 
  143. color unless the blink bit is disabled.  In addition to these 16 colors,
  144. DEFAULT can be specified for either/both foreground or background.  This
  145. will restore the color to its default state. (As specified by color_default
  146. or the program if color_default is not used).  For example if our default
  147. colors are WHITE on BLACK and we specify `color(RED,BLACK);  followed later
  148. by `color(DEFAULT,GREEN); we will then have WHITE on GREEN.
  149.  
  150. CO:  `co(foreground #,background #);
  151.   This command operates identically to color but is a short form version
  152. and is preferable where many color commands are used.  In this form we
  153. specify the colors with their decimal value 0-15 instead of a much longer
  154. text string.  For example, instead of `color(LIGHTGRAY,GREEN); we would
  155. have `co(7,2);  If many commands exists in a file this saves both space
  156. and time when the text is displayed, as the help engine does not have to
  157. search for the color string.  This also accepts default parameters but
  158. in this form you simply use a ? i.e. `co(?,3);  In addition, this form
  159. allows you to completely exclude the parameters and restore the default
  160. foreground and background with the simple call `co();  This is preferable
  161. since it then allows you greater flexibility is changing the default 
  162. colors without having to search and replace all color commands that 
  163. restore the defaults.
  164.  
  165. CK:  `ck(foreground #,background #);
  166.   This command is the same as co except that the first character following
  167. the command is displayed in the attribute specified by the color_first_char
  168. command (or the program if color_first_char is not used).  This is used
  169. internally by the help engine and is not normally needed.
  170.  
  171. COLOR_DEFAULT:  `color_default(foreground string,background string);
  172.   This command specifies the default foreground and background colors.
  173. This command is not required unless the program default is to be overidden.
  174. If it is used, it should be on the first line in the help file.
  175.  
  176. COLOR_FIRST_CHAR:  `color_first_char(foreground string,background string);
  177.   This command specifies the color of the first character of all keywords.
  178. This command is not required unless the program default is to be overidden.
  179. If it is used, it should be on the first line in the help file.
  180.  
  181. COLOR_HILITE:  `color_hilite(foreground string,background string);
  182.   This command specifies the color of the keyword when the cursor selects it.
  183. This command is not required unless the program default is to be overidden.
  184. If it is used, it should be on the first line in the help file.
  185.  
  186. COLOR_KEYWORD:  `color_keyword(foreground string,background string);
  187.   This command specifies the color of the keyword itself.
  188. This command is not required unless the program default is to be overidden.
  189. If it is used, it should be on the first line in the help file.
  190.   
  191. SOUND:  `sound(frequency,duration);
  192.   This routine causes the speaker to sound at the desired frequency for the
  193. specified duration in clock ticks (91/second) when this line is displayed. 
  194. It is useful in specifying the end of file and other important segments
  195. within the help file.
  196.  
  197. DELAY:  `delay(duration);
  198.   This routine causes the program to pause for the specified duration in
  199. clock ticks (91/second) when this line is displayed and is useful for
  200. animation, etc.
  201.  
  202. DOS:  `dos(command line);
  203.   This routine causes the DOS program to be executed when the line containing
  204. this command is displayed.  Note that this is different from the DOS command
  205. within a keyword, as this occurs on display, and the keyword version only
  206. occurs if the user selects the keyword and presses <Enter>.
  207.  
  208. BLINK:  `blink(state);  (EGA/VGA only)
  209.   This routine turns the blink enable bit on or off depending on "state".
  210. To disable blinking, use 0, to enable, use 1.  Turning this bit off
  211. allows all 256 possible color combinations to be used without the high
  212. intensity background colors blinking.  If this function is used, it should
  213. be on the first line in the help file.
  214.  
  215. FONT:  `font(fontname,block);  (EGA/VGA only)
  216.     This routine loads the desired font into the specified "block".  Block
  217. 0 is the primary font, block 1 is the font selected by usig the high
  218. intensisty colors.  (See the UltraWin documentation for more details).
  219. If this function is used, it should be on the first line in the help file.
  220. Once the font command is encountered, it is "disable" so that each time
  221. the line is displayed the font will not be reloaded and the screen reset.
  222.  
  223. TAB:  `tab(value);
  224.     This routine sets the tab size for the given file.  The default value
  225. is 2.  If this function is used, it should be on the first line in the
  226. help file. (Or before any tabs occur).
  227.  
  228. - END -
  229.